Creating Wizard Definition Pages

The first step in building a custom wizard is to write a VTML file to define the interface and output parameters. This section describes the VTML tags used in this part of the process and presents an example definition file.

Note

Whenever you make changes to a VTM file or create a new one, save the file, then press Ctrl+Alt+Shift+C to apply the changes.

VTML for Wizards tag summary

The following is the hierarchy of the tag set for wizard definition files:

WIZARD -- The enclosing tag for the entire file; it defines the new wizard with a name, caption and default image.

PARAM -- When used as a sub-tag of the WIZARD tag, it defines a parameter that the wizard uses to generate its output. These parameters are then available for use with wizard output templates.

TEMPLATE -- Defines an output template and identifies the file used for text output.

PAGE -- Defines a wizard page that determines which page class to load.

PARAM -- When used as a sub-tag of the PAGE tag, it sets the behavior of a page class. This is useful for standard pages which are intended to be re-used across multiple wizards.

INPUT -- Defines an input control on a wizard page. If the NAME attribute of the INPUT control matches both the name of a control on the wizard page as well as the name of a PARAM defined within the WIZARD tag then the control is automatically `bound' to the underlying parameter without requiring any explicit code.

NEXTPAGE -- The NEXTPAGE tag allows for complex routing between pages based on the value of conditional expressions.

PAGELAYOUT -- Same as VTML syntax for containers and controls.

VTML for Wizards tag reference

The following tables provide the complete VTML syntax for writing wizard definition files.

The following table describes the WIZARD tag.


Attribute	Description
NAME	Optional. Used to resolve the names of pages that belong to a specific wizard. May be registered using the syntax `WizardName.PageName.`
CAPTION	Optional. Caption to display in the wizard's title bar.
IMAGE	Optional. Default bitmap to use for pages within the wizard.

The following table describes the PARAM tag for the WIZARD tag.


Attribute	Description
NAME	Name of the parameter.
VALUE	Initial value of the parameter.
REQUIRED	Optional. The wizard manager will not enable the Finish button until all required parameters are entered.

The following table describes the TEMPLATE tag.


Attribute	Description
NAME	File name of the wizard (.wml) output template.
OUTPUTFILE	Name of the file to which output to based on the results of processing the template.
OUTPUTPATH	Optional. Output directory for the file. Defaults to the value of the variable `LOCATION`. Note that you must provide a wizard page where the user can specify this value.
DESCRIPTION	Optional. Description of the wizard page's function for use in the output summary page.

The following table describes the PAGE tag.


Attribute	Description
TYPE	Required for dynamic wizards. "Dynamic" - VTML layout)
NAME	Name of the page.
CAPTION	Caption to display in the top portion of the page.
IMAGE	Optional. Override of the default wizard bitmap.
CONDITION	Optional. Conditional expression which determines if the page is displayed.
NEXTPAGE	Optional. Name of page to go to after the current one. The default page is to the next page defined in the configuration file.

The following table describes the PAGELAYOUT tag.


Attribute	Description
Similar to EDITORLAYOUT in VTML
None

The following table describes the PARAM tag for the PAGE tag.


Attribute	Description
NAME	Name of the parameter.
VALUE	Value of the parameter.
REQUIRED	True/False or YES/NO (can be the result of a dynamic expression). Determines whether a value for the parameter is required. The Wizard manager will not enable the Finish button until all required parameters are entered.

The following table describes the INPUT tag.


Attribute	Description
NAME	Name of the form control to which the `INPUT` is bound.
PARAM	Optional. Name of parameter to which the `INPUT` is bound. Defaults is the NAME attribute).
DEFAULT	Optional. Default value for the input.
REQUIRED	Optional. Is the input required?
VALIDATIONMSG	Optional. A message to display to the user if the input is required and a value is not entered.
LISTCONTENTS	Optional. If this is TCustomListBox or TCustomComboBox based input, then a comma-separated list will be used to populate the list with values.

The following table describes the NEXTPAGE tag.


Attribute	Description
NAME	Name of a page to go to next.
CONDITION	Conditional expression that determines whether to go to the page. If multiple NEXTPAGE tags are specified, then the first one to match a CONDITION will be the next page.

Dynamic expressions in tags

Any tag attribute may combine static, constant text with embedded dynamic expressions that reference parameters or input controls. To embed an expression within a text string, the following syntax is utilized:

$${ expression }

So, for example, to set the REQUIRED attribute of a parameter based on whether another value was set, you would use the following syntax:

<PARAM NAME="RowsPerPage" VALUE="10" 

    REQUIRED="$${ ParameterExists('Customize') }">

Or, to customize the OUTPUTFILE attribute of the TEMPLATE tag using a name attribute entered by the user, you would use the following syntax:

OUTPUTFILE="$${Name}Admin.cfm">

The expression syntax supported within the wizard configuration file is the same as the one supported in wizard output templates (see the reference section for more details).

Bound controls

One of the most powerful capabilities of wizard pages are bound controls. Bound controls allow you to place controls onto the wizard page and have their values automatically bound to wizard parameters. To do this, simply add an INPUT sub-tag to the PAGE tag for each control you wish to bind, making sure that the NAME attribute of the INPUT tag matches the Name property of the control. All controls specified in the layout can be bound.

Wizard definition page example

This sample wizard creates an HTML template.

<WIZARD NAME="DefaultTemplate" CAPTION="Default HTML Template">



<!--- wizard parameters --->

<PARAM NAME="sDocType" VALUE="HTML 4.0" REQUIRED="true">

<PARAM NAME="sTitle" VALUE="">

<PARAM NAME="bMetaDescr" VALUE="false">

<PARAM NAME="sMetaDescr" VALUE="">

<PARAM NAME="bMetaKeywords" VALUE="false">

<PARAM NAME="sMetaKeywords" VALUE="">



<!--- WIZARD PAGE --->



<!--- attributes page --->

<PAGE NAME="DocAttribs" TYPE="DYNAMIC"

    CAPTION="HTML Document Attributes"

    IMAGE="..\\images\\main.bmp">



    <PAGELAYOUT>

        <CONTROL NAME="lblDocType" TYPE="label"

            DOWN="10" RIGHT="10"

            WIDTH="90"

            CAPTION="Document Type:"

        />



        <CONTROL NAME="ddDocType" TYPE="DropDown"

            EDITABLE="no"

            ANCHOR="lblDocType" corner="NE" WIDTH="MAXIMUM" down="-5">

                    <ITEM CAPTION="HTML 2.0" VALUE="HTML 2.0"/>

                    <ITEM CAPTION="HTML 3.2" VALUE="HTML 3.2"/>

                    <ITEM CAPTION="HTML 4.0" VALUE="HTML 4.0"/>

        </CONTROL>



        <CONTROL NAME="lblTitle" TYPE="label"

            ANCHOR="lblDocType" CORNER="SW" down="20"

            WIDTH="90"

            CAPTION="Title:"

        />




        <CONTROL NAME="tbTitle" TYPE="TextBox"

            ANCHOR="lblTitle" CORNER="NE" WIDTH="MAXIMUM" down="-5"

        />



    <CONTAINER NAME="pnlMetaDescription" TYPE="Panel"

            CAPTION="Meta Description"

            ANCHOR="lblTitle" CORNER="SW" DOWN="20"

            WIDTH="MAXIMUM" MAXWIDTHPADDING="10" HEIGHT="80"

                LFHEIGHT="90">



            <CONTROL NAME="chkMetaDescr" TYPE="CheckBox"

                CAPTION="Add meta description:"

                DOWN="20" RIGHT="15"

                WIDTH="MAXIMUM"/>



            <CONTROL NAME="tbMetaDescr" TYPE="TextBox"

                ANCHOR="chkMetaDescr" CORNER="SW" DOWN="8"

                WIDTH="MAXIMUM"/>



        </CONTAINER>



    </PAGELAYOUT>



    <INPUT NAME="ddDocType" PARAM="sDocType">

    <INPUT NAME="tbTitle" PARAM="sTitle" REQUIRED="yes" 
VALIDATIONMSG=

        "Please enter a document title" or some equivalent message>

    <INPUT NAME="chkMetaDescr" PARAM="bMetaDescr">

    <INPUT NAME="tbMetaDescr" PARAM="sMetaDescr">

</PAGE>



<!--- attributes page --->

<PAGE NAME="MetaKeywords" TYPE="DYNAMIC"

    CAPTION="Meta Keywords"

    IMAGE="..\\images\\main.bmp">



    <PAGELAYOUT>



        <CONTROL NAME="chkMetaKeywords" TYPE="CheckBox"

            CAPTION="Add meta keywords:"

            DOWN="15" RIGHT="10"

            WIDTH="MAXIMUM"/>



        <CONTROL NAME="taMetaKeywords" TYPE="TextArea"

            ANCHOR="chkMetaKeywords" CORNER="SW" down="10"

            HEIGHT="MAXIMUM" width="MAXIMUM"/>



    </PAGELAYOUT>



    <INPUT NAME="chkMetaKeywords" PARAM="bMetaKeywords">

    <INPUT NAME="taMetaKeywords" PARAM="sMetaKeywords">



</PAGE>




<!--- OUTPUT TEMPLATE --->



<TEMPLATE

    NAME="Custom.wml"

    OUTPUTFILE="MyFile.cfm"

    DESCRIPTION="New HTML file">



</WIZARD>

Customizing the Development Environment
Customizing the Development Environment